<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<title>EasyRTC Documentation</title>
	<link href="assets/easyrtc-docs-styles-1.css" media="all" rel="stylesheet" />
</head>
<body>
<header class="template">
	<div class="wrapper-content">
    <a href="./index.html"><img src="assets/easyrtc-logo.png" alt="EasyRTC Documentation"></a>
		<h1 title="EasyRTC Documentation">Documentation</h1>
	</div>
</header>
<div class="wrapper-docs">
<nav>
	<h2><a href="./index.html">Docs Home</a></h2>
	<h3>EasyRTC Guides</h3>
	<ul>
		<li><a href="easyrtc_faq.html">FAQ</a></li>
		<li><a href="easyrtc_gettingStarted.html">Getting Started</a></li>
		<li><a href="easyrtc_server_install.html">EasyRTC Server: Installation</a></li>
		<li><a href="easyrtc_client_tutorial.html">EasyRTC Framework Tutorial</a></li>
		<li><a href="easyrtc_rooms.html">Rooms</a></li>
		<li><a href="easyrtc_server_configuration.html">EasyRTC Server: Configuration</a></li>
		<li><a href="easyrtc_server_events.html">EasyRTC Server: Events</a></li>
		<li><a href="easyrtc_server_ice.html">EasyRTC Server: ICE Configuration</a></li>
		<li><a href="easyrtc_with_other_servers.html">Using Alongside Other Servers</a></li>
		<li><a href="easyrtc_server_ssl.html">EasyRTC Server: Using SSL</a></li>
		<li><a href="easyrtc_webrtc_problems.html">WebRTC Problems and Possible Fixes</a></li>
		<li><a href="easyrtc_upcoming_features.html">Upcoming Features</a></li>
		<li><a href="easyrtc_changelog.html">Change Log</a></li>
	</ul>

	<h3>EasyRTC Client Classes</h3>
	<ul>
		<li><a href="client-api/Easyrtc.html">Easyrtc</a></li>
		<li><a href="client-api/Easyrtc_App.html">Easyrtc_App</a></li>
		<li><a href="client-api/Easyrtc_ft.html">Easyrtc_ft</a></li>
		<li><a href="client-api/Easyrtc_IframeCapture.html">Easyrtc_IframeCapture</a></li>
		<li><a href="client-api/Easyrtc_No_IframeCapture.html">Easyrtc_No_IframeCapture</a></li>
		<li><a href="client-api/Easyrtc_Rates.html">Easyrtc_Rates</a></li>
		<li><a href="client-api/Easyrtc_Recorder.html">Easyrtc_Recorder</a></li>
	</ul>
	<h3>EasyRTC Server Modules</h3>
	<ul>
		<li><a href="server-api/module-easyrtc_default_event_listeners.html">easyrtc_default_event_listeners</a></li>
		<li><a href="server-api/module-easyrtc_default_options.html">easyrtc_default_options</a></li>
		<li><a href="server-api/module-easyrtc_private_obj.html">easyrtc_private_obj</a></li>
		<li><a href="server-api/module-easyrtc_public_obj.html">easyrtc_public_obj</a></li>
		<li><a href="server-api/module-easyrtc_util.html">easyrtc_util</a></li>
		<li><a href="server-api/module-general_util.html">general_util</a></li>
	</ul>
	<h3>EasyRTC Server Classes</h3>
	<ul>
		<li><a href="server-api/module-easyrtc_default_event_listeners-eventListener.html">eventListener</a></li>
		<li><a href="server-api/module-easyrtc_public_obj-pub.html">pub</a></li>
		<li><a href="server-api/module-easyrtc_public_obj-pub.events.html">events</a></li>
		<li><a href="server-api/module-easyrtc_public_obj-pub.util.html">util</a></li>
		<li><a href="server-api/module-easyrtc_util-eu.html">eu</a></li>
		<li><a href="server-api/module-general_util-g.html">g</a></li>
		<li><a href="server-api/pub.appObj.html">appObj</a></li>
		<li><a href="server-api/pub.appObj.connectionObj.html">connectionObj</a></li>
		<li><a href="server-api/pub.appObj.connectionObj.connectionRoomObj.html">connectionRoomObj</a></li>
		<li><a href="server-api/pub.appObj.roomObj.html">roomObj</a></li>
		<li><a href="server-api/pub.appObj.sessionObj.html">sessionObj</a></li>
	</ul>
</nav>
<div class="easyrtc-docs-content">
<h1>EasyRTC: Authentication</h1>

<p>By default EasyRTC allows all connections, however it can be locked down to work against a variety of authentication methods. Most commonly this is done by sending a username and credential upon connecting to the server.</p>

<p>Even if authentication is not needed, setting the username can be used to create a visible alternative to the easyrtcid.</p>

<h2>Setting Username and Credential in JS Client</h2>

<p><strong>easyrtc.setUsername()</strong></p>

<ul><li>Use before connecting to the server via <code>easyrtc.connect()</code> or <code>easyrtc.easyApp()</code></li><li>Shared to other connections in the same room<ul><li>Can be used for setting a visible name (instead of easyrtcid)</li><li>To avoid sharing username, embed it inside the credential via <code>easyrtc.setCredential()</code></li></ul></li><li>Restricted by regular expression<ul><li>Default is to allow up to 64 of any characters. </li><li>In client JS, set <code>easyrtc.usernameRegExp</code></li><li>In server, set option <code>usernameRegExp</code></li></ul></li><li>Usernames should not be considered unique to a connection. One user could have multiple connections open. </li><li><p>Value is sent to the server &quot;authenticate&quot; event listener  </p><p>easyrtc.setUsername(&quot;handsomeJack&quot;);</p></li></ul>

<p><strong>easyrtc.setCredential()</strong></p>

<ul><li>Use before connecting to the server via <code>easyrtc.connect()</code> or <code>easyrtc.easyApp()</code></li><li>Can contain any JSONable object</li><li><p>Value is sent to the server &quot;authenticate&quot; event listener  </p><p>easyrtc.setCredential({
  &quot;password&quot;:&quot;345RTC!&quot;,
  &quot;realm&quot;:&quot;easyrtc.com&quot;,
  &quot;apikey&quot;:&quot;d834kds81vs189s10kkd4&quot;
});</p></li></ul>

<h2>Checking Authentication On Server</h2>

<p><strong>Using &quot;authenticate&quot; Event Listener</strong></p>

<p>The &quot;authenticate&quot; event is fired during the initial connection. The listener is provided with full details about the connection, so it may decide whether to authenticate or disconnect them.</p>

<p>In this simplistic example, any clients connecting to the adminSite application will be denied unless they have a username of &quot;handsomeJack&quot;. Any clients connecting to any other application will be let through.</p>

<pre><code>var onAuthenticate = function(socket, easyrtcid, appName, username, credential, easyrtcAuthMessage, next){
  if (appName == &quot;adminSite&quot; &amp;&amp; username != &quot;handsomeJack&quot;){
    next(new easyrtc.util.ConnectionError(&quot;Failed our private auth.&quot;));
  }
  else {
    next(null);
  }
};

easyrtc.events.on(&quot;authenticate&quot;, onAuthenticate);</code></pre>

<p><strong>Listener Parameters:</strong></p>

<ul><li><strong>socket</strong><ul><li>Socket.io object for the specific socket connection </li><li>The IP Address of the connection is available from <code>socket.handshake.address.address</code></li><li>If using a proxy, the IP may be available from <code>socket.handshake.headers[&#39;x-forwarded-for&#39;]</code></li><li>Referer <em>may</em> be available from <code>socket.handshake.headers.referer</code></li><li>The socket can be disconnected using <code>socket.disconnect()</code> however it is recommended to call next() with an error</li></ul></li><li><strong>easyrtcid</strong><ul><li>A unique identifier given to this connection</li></ul></li><li><strong>appName</strong><ul><li>The requested EasyRTC application. Useful for application specific authentication.</li></ul></li><li><strong>username</strong><ul><li>Shared to other connections in the same room<ul><li>Can be used for setting a visible name (instead of easyrtcid)</li><li>To avoid sharing username, embed it inside the credential via <code>easyrtc.setCredential()</code></li></ul></li><li>Restricted by regular expression<ul><li>Default is to allow up to 64 of any characters. </li><li>In client JS, set <code>easyrtc.usernameRegExp</code></li><li>In server, set option <code>usernameRegExp</code></li></ul></li></ul></li><li><strong>credential</strong><ul><li>Depending on authentication method, may be used for storing passwords, realms, hashes, apikeys, etc. </li><li>Can be any JSONable object</li><li>Type checking should be performed </li></ul></li><li><strong>easyrtcAuthMessage</strong><ul><li>Includes the complete authentication message sent by the client</li><li>May be used to deny authentication based on requested rooms, api fields, etc. </li></ul></li><li><strong>next</strong><ul><li>A callback function which should be called once (and only once)</li><li>If client should be authenticated, call with a null parameter<ul><li><code>next(null);</code></li></ul></li><li>If client should not be authenticated, call with an Error for the parameter<ul><li><code>next(new easyrtc.util.ConnectionError(&quot;Failed our private auth.&quot;));</code>    </li></ul></li></ul></li></ul>

<p>For more information about EasyRTC server events, see <a href="easyrtc_server_events.md">easyrtc<em>server</em>events.md</a></p>

<h2>If You Run Into Problems</h2>

<p>Please feel free to post on our discussion forum:</p>

<ul><li><a href="https://groups.google.com/forum/?fromgroups#!forum/easyrtc">https://groups.google.com/forum/?fromgroups#!forum/easyrtc</a></li></ul>

	</div>
</div>
<footer class="template">
	<div class="wrapper-content">
		<p>Copyright &copy;2016 EasyRTC</p>
	</div>
</footer>
</body>
</html>